NYSED A-Series WWW CGI Library Version 2.0B CGILIB SPECS December 12, 1997 PREREQUISITES: A. You are running COMS. B. You are running the NYSED-A-Series Web Server **Version 2.0A** or higher! INSTALLATION: 1. Create the source file on the A-Series. The library source code is written in ALGOL so make sure that the file is saved as type ALGOL. 2. Compile the library. The code file name does not matter. As an example assume the code file is named (USER)SYSTEM/CGILIB. 3. Set the file security. If the CGI library will be used by applications running under multiple usercodes, then you will need to modify the file security. From a CANDE session use the command: SECURITY (USER)SYSTEM/CGILIB ON WEBFAMILY PUBLIC IN 4. SL the library. The library must be SLed from the ODT or a remote ODT session. If you wish to use the sample CGI applications then you should SL it as CGILIB. Sample ODT comand follows: SL CGILIB = (USER)SYSTEM/CGILIB ON WEBFAMILY 5. Try a test application. Test a sample CGI application. Remember it must be defined with COMS Utility in the normal manner for any COMS application. If you experience application problems with new applications, you may wish to uncomment some displays that can be found in the CGI library to assist in troubleshooting. Don't forget steps 3 & 4 above after you recompile! CGI DIAGRAM: ------------------------------------------- | | | C O M S | | ......................>. | ---------:----------------------:---------- (COMS SEND) : : : --------------- (Envronment | WWW Server | Information) --------------- : | V -------------- --------------- ------------------- | Web | | Request | CGI |CGI| COMS | | Client |<=TCP/IP=>| Handler |<=PORT==>|LIB| CGI | | (Browser) | | | FILE | | Application | -------------- --------------- ------------------- CGILIB OVERVIEW: A system library (CGILIB) has been developed to simplify the CGI port interface for CGI applications. The CGILIB allows the CGI application to request a "list of fields" and define the lengths and order that they are to be returned so that the CGI application does not have to do any string searches. The CGI app can request any field that may appear in the Environment (ie: REMOTE_HOST), Request Header (ie: User-Agent), or Request Contents (ie: from HTML Input Form). If the request is a GET request (ie: there are no contents), the CGILIB treats the QUERY_STRING as the Contents so the CGIapp does not need to determine whether the request is a GET or POST request. The CGILIB takes care of extracting the CGI port name from the COMS message and assigning it to the CGI port file. The CGILIB allows CGI applications to easily access WWW input transactions without having to deal with the HTTP protocol, URL encoded form input, string searching to locate input fields, or even having to determine whether the transaction came in with a GET or a POST method. Full access is allowed to all request header fields just as easily as if they were part of the normal form input fields. CGILIB CGI_FORM Service: The CGILIB provides a number of services for CGI applications. The main input service, CGI_FORM, allows a CGI app to make a single library call to receive web input and accomplish the following: 1. Title the CGI port file to the correct port name provided in the COMS message from the web server. 2. Determine the number of bytes in the request header and read them in from the CGI port file. 3. Determine the number of bytes in the content part of the request and read them in from the CGI port file. Chunked contents are now supported. 4. Decode any urlencoded input. Input is normally urlencoded which means that most non-alpha characters come in as a percent sign (%) followed by an ASCII hex code. 5. Pick through the Request Header for fields that the CGI app desires. 6. Pick through the CGI Environment fields that the CGI app desires. 7. Pick through the contents of the request for specific input fields. 8. Size all desired fields to the fixed length that the CGI app wants. 9. Order all requested fields to the specification of the CGI app. 10. Place the input into a single array in the requested format and return it to the CGI app. CGI INPUT FORMATTING: An array is passed to CGI_FORM to specify how the input fields should be returned. It is a comma seperated list of field names and sizes: FIELD1,SIZE1,FIELD2,SIZE2.... Example: FNAME,20,LNAME,20..... ANY field present in the Request Header from the client, the CGI Environment Message or the Contents from the client may be specified in the input format. The above list is in the order that they are searched, so if you use a Request Header field name in your HTML form, you will get the header field and not the HTML field! CGILIB WRITE_PORT Service: The CGILIB main output service, WRITE_PORT, buffers output for the CGI app and assumes the responsibility for CGIPORT error handling. The CGI app is fully responsible for the creation of the output data. RESPONSE MESSAGES FROM THE CGI APPLICATION VIA THE CGI PORT: The CGI app must send a short header which may be followed by contents such as an HTML document. RESPONSE HEADER FIELDS: These are sent from the CGI app to the request handler preceeding any contents such as an HTML document. The response header fields recognized by the NYSED web server are: Content-Type: REQUIRED if there are contents Content-Length: OPTIONAL if there are contents Location: Results in a "302 Move Temp" response Status: **Now supported** The examples that follow, show how this is accomplished: 1. Content-Type: text/htmlHTML Document follows... 2. Location: http://www.nysed.gov/some/other/doc.html 3. Status: 205 Reset Content A pair of s terminates the response header as per the HTTP specs. If the CGI app does not send a response header to the server, the server will guarantee that an error response is sent to the client. HOW THE NYSED WEB SERVER HANDLES RESPONSE HEADER FIELDS: The response header fields provided by the CGI applications determine how the web server handles the response. The web server checks for the header fields in the following order: 1. If the 'Status' field is present then that is used to indicate the result to the client. The web server allows contents to follow, but it is up to the client application to know for which status codes that contents are (and are not) apropriate. Also there must be a 'Content-Type' header field included if there are contents. 2. Otherwise, if the 'Location' field is present then a '302 Move Temp' result is returned. The web server allows contents to follow in which case there must be a 'Content-Type' header field included. 3. Otherwise, if the 'Content-Type' field is present then a '200 OK' response is sent to the client with the contents that are expected to follow. An additional 'Content-Length' header field is beneficial but optional. 4. If none of the above fields are received then the web server returns a '501 Service Unavailable' response after the timeout configured in the WWWSERV/COMS/CONFIG file. CGI TIMEOUTS: The overall transaction timeout is determined by the Timeout setting configured in the WWWSERV/CONFIG file. The Application Timeout configured in COMS/CONFIG file is used as an 'inactive' timeout for the CGI app. Related Files: The use of the CGILIB is shown in related sample COBOL74 and ALGOL Applications and documented with comments.